Decouple App Hang backtrace generation from Crash Reporting - #3136

What and why?

Until now, the only way to stop generating stack traces for App Hangs was to not link DatadogCrashReporting at all — which also gave up crash reports. CrashReporting.enable(in:) is what registers BacktraceReportingFeature in core, and AppHangsWatchdogThread calls into it unconditionally, so there was no supported way to have both real crash reports and App Hang errors without stack traces.

Two customer motivations:

1. Performance. Generating the backtrace snapshots all running threads while the main thread is still blocked, so its cost is added to the very hang being measured. RUM.Configuration.appHangThreshold supports sub-second values (minimum 0.1s), so this cost can be a meaningful fraction of the reported hang duration. Apps tuned to a small threshold may not want to pay it.
2. Privacy / policy. Some apps are not permitted to collect thread stacks but still want crash reports and hang counts.

This is an iOS-specific gap. For context on why no equivalent flag is being added elsewhere: on Android, ANR backtraces are self-contained in the RUM module (Thread.getAllStackTraces() in the ANR detector, and ApplicationExitInfo for fatal ANRs) and never depend on a separate crash-reporting module being installed, so the coupling does not exist there. Android's ANR threshold is also a fixed 5000ms, which makes the same backtrace cost negligible — whereas iOS explicitly supports sub-second thresholds. Wrappers (React Native / Flutter / KMP / Unity) call CrashReporting.enable(in:) and so keep the default; surfacing the option per-wrapper is separate, opt-in work.

CHANGELOG.md has a [FEATURE] entry under # Unreleased.

How?

The new option lives on Crash Reporting, not RUM.Configuration, because backtrace generation is a Crash Reporting capability — RUM only consumes it. RUM.Configuration.appHangThreshold stays purely about detection.

// Crash reports: yes. App Hang stack traces: no.
CrashReporting.enable(with: .init(appHangBacktraceEnabled: false))

The flag travels through DatadogInternal, since DatadogCrashReporting and DatadogRUM must not import each other:

CrashReporting.Configuration.appHangBacktraceEnabled
  → core.register(backtraceReporter:appHangBacktraceEnabled:)   [DatadogInternal]
  → BacktraceReportingFeature.appHangBacktraceEnabled           [DatadogInternal]
  → core.isAppHangBacktraceEnabled  (lazy, order-independent)
  → AppHangsWatchdogThread.isAppHangBacktraceEnabled: () -> Bool [DatadogRUM]
  → AppHang.BacktraceGenerationResult.disabled

Every API change is purely additive

No existing declaration gained a defaulted parameter, because that changes the compound name and the mangled symbol even though ordinary call sites keep compiling. CrashReporting.enable(in:) and core.register(backtraceReporter:) are kept as their own declarations, and the new forms are overloads next to them:

Keeping enable(in:) separate is also required rather than merely preferred: a default value on configuration would make the existing CrashReporting.enable() call ambiguous.

Note for future changes in this area: make api-surface-verify would not have caught a symbol change in DatadogInternal, because that module is not in DATADOG_MODULES (Makefile:414) and so none of its public surface is tracked in api-surface-swift. The additions above were kept additive by hand. The flip side is that they do not widen the customer-facing API surface either.

Notable points

• BacktraceReportingFeature is still registered when the flag is false. That feature is shared by crash reports, error.binary_images on RUM view events, binaryImages on error logs, and the public core.backtraceReporter API — so the flag cannot be implemented by skipping registration. Only the App Hangs watchdog path is gated.
• The registration slot is single, and the default path never claims it. Both register(backtraceReporter:…) and register(appHangBacktraceEnabled:) no-op when a BacktraceReportingFeature is already registered. So the reporter-less register(appHangBacktraceEnabled:) is called only when a custom plugin provides no backtrace reporter and the app opted out — the one case where there is a policy worth recording. With the default, nothing extra is registered and a reporter registered later still installs, exactly as on develop.
• Resolved lazily, per hang, not captured when AppHangsMonitor is constructed, so CrashReporting.enable may be called before or after RUM.enable. A @Sendable () -> Bool closure is injected into the watchdog thread (defaulting to { true }), keeping the hot loop free of feature lookups it does not own and the unit under test injectable.
• "Disabled" and "unavailable" are deliberately distinct states. Reporting "DatadogCrashReporting had not been enabled" to someone who did enable it and opted out of hang backtraces would be misleading, so .disabled carries its own error.stack message. Never enabling Crash Reporting still yields the pre-existing message.
• AppHang.BacktraceGenerationResult gains a case. It is Codable and fatal hangs are persisted at hang start and replayed on next launch; existing cases keep their synthesized keys, so hangs persisted by an earlier SDK version still decode.
• Behavior change, deliberate: previously, if the watchdog could not resolve the main thread's ThreadID it reported telemetry and dropped the hang entirely. With backtraces disabled the thread ID is not needed, so the hang is now reported instead of dropped.

No default behavior changes — an app that does not touch the new option behaves exactly as before.

Resulting App Hang error fields:

The last two rows are pre-existing and covered by untouched tests.

Example app. It never set appHangThreshold, so App Hangs were not detected there at all and the flag had no reachable effect. The second commit sets a 0.5s threshold and adds an "App Hang" section to the Crash Reporting debug screen with a "Hang main thread for 2s" button. The flag is fixed at CrashReporting.enable time so it cannot be a runtime toggle — it reads a DD_DISABLE_APP_HANG_BACKTRACES launch argument instead, matching the existing Environment.Argument pattern, and a label shows which state is active.

Feature docs. DatadogRUM/RUM_FEATURE.md is re-verified in its own commit: DatadogRUM/Sources/RUMConfiguration.swift is one of its tracked_files and this branch amends the appHangThreshold doc-comment, so make feature-docs-verify failed until the App Hangs entries and the frontmatter baseline were updated.

How to validate

make dependencies && make repo-setup
make test-ios SCHEME="DatadogRUM"
make test-ios SCHEME="DatadogCrashReporting"
make test-ios SCHEME="DatadogCore"              # ObjC API tests
make test-ios SCHEME="DatadogIntegrationTests"
make api-surface-verify
make feature-docs-verify
./tools/lint/run-linter.sh

All green locally with this branch rebased onto develop: DatadogRUM 777 tests, DatadogCrashReporting 64 (1 pre-existing skip), DatadogCore 764, DatadogIntegrationTests 211 — 0 failures; linter 0 violations in 677 files; api-surface (Swift + ObjC) up to date, delta vs develop is 8 insertions and 0 deletions; all 5 *_FEATURE.md docs verified.

Twelve added tests, each confirmed passing by name:

The two enablement orders are separate tests rather than one randomized case: only the RUM-first order proves the opt-out is read per hang instead of captured when RUM is enabled, so randomizing would let that regression pass roughly half of CI runs.

DDConfiguration+apiTests.m also gained assertions on the DDCrashReporterConfiguration default value and setter write-through, and TestUtilities' BacktraceReporterMock gained a generation counter so "never invoked" is assertable.

Manual check in the Example app: Debug Crash Reporting with RUM → "Hang main thread for 2s", then relaunch with the DD_DISABLE_APP_HANG_BACKTRACES launch argument and compare error.stack between the two runs.

No Synthetics e2e scenario was added: E2ETests/ has no App Hangs scenario for any App Hang behavior today, its assertions live in server-side monitors rather than in this repo, and deliberately hanging the main thread sits poorly with how those scenarios are driven. The AppHangsMonitoringTests cases above are the deepest in-repo coverage.

Known, out of scope

objc_CrashReporting and objc_CrashReportingConfiguration live in DatadogCrashReporting/Sources/CrashReporting.swift rather than in a +objc.swift file. The api-surface generator routes by filename suffix, so this module's Objective-C surface is absent from api-surface-objc and its members instead appear un-indented in api-surface-swift. That predates this PR; moving the existing type is a separate change.

Review checklist

• Feature or bugfix MUST have appropriate tests (unit, integration)
• Make sure each commit and the PR mention the Issue number or JIRA reference — no JIRA ticket exists for this work; flagging for a reviewer to attach one if required
• Add CHANGELOG entry for user facing changes
• Add Objective-C interface for public APIs - see our guidelines (internal) — DDCrashReporterConfiguration + DDCrashReporter.enableWith:
• Run make api-surface when adding new APIs